Docusaurus로 블로그 개설하기 - 1. 개요
개요
1) 도큐사우루스를 선택한 이유
평소 회사에서나 개인적으로 개발을 하다 보면 프로젝트에 대한 정리는 중요한 업무 중 하나다.
예전에 진행했던 프로젝트와 비슷한 작업을 해야 할 때나, 한동안 접어두었던 프로젝트를
다시 시작할 때면 관련 내용이 잘 기억나지 않는 경우가 많았다.
특히 급하게 진행하느라 문서화가 제대로 되지 않은 프로젝트를 다시 들여다볼 때면,
모든 내용을 처음부터 다시 찾아보고 검색해야 했다.
순간 순간의 귀찮음들이 쌓여 그대로 기술 부채가 되었다.
물론 README와 주석만 잘 작성해도 어느 정도는 괜찮을 것이다.
하지만 세부적인 설정 사항이나 업무 진행 과정이 프로젝트별로 잘 정리되어 있다면,
나중에 비슷한 프로젝트를 할 때 참고하기도 좋고 팀원들도 쉽게 내용을 확인할 수 있을 것이다.
인수인계할 때도 훨씬 수월할 것이고, 문서를 보면서 프로젝트의 개선점도 찾을 수 있으리라 본다.
이런 이유로 여러 문서화 도구를 사용해봤다. 갤럭시 노트부터 시작해서 에버노트, 노션, 옵시디언까지 다양한 툴을 써봤다. 그중에서도 컨플루언스는 문서 구조화가 잘 되어있어서 특히 자주 사용했었다.
개인 블로그로는 티스토리를 이용했었는데, 바쁜 일상과 출퇴근 시간에 치여 한동안 방치해두었다. 그러다 새해를 맞아 기술 블로그 스터디를 시작하게 되었고, 도큐사우루스라는 프레임워크를 추천받아 관심을 갖게 되었다.
2) 도큐사우루스(Docusaurus)란?
도큐사우루스는 페이스북(현 메타)에서 만든 정적 웹사이트 생성기다.
처음에는 오픈소스 프로젝트의 문서화를 위해 만들어졌지만,
지금은 기술 블로그나 개인 웹사이트를 만드는 데에도 많이 사용되고 있다.
마크다운으로 글을 작성하면 자동으로 웹사이트를 만들어주는데, 개발자들이 좋아할 만한 기능들이 많이 있다.
코드 하이라이팅이 기본으로 지원되고, 버전 관리도 쉽게 할 수 있다.
게다가 React로 만들어져서 필요한 기능을 직접 추가하기도 좋다.
도큐사우루스의 장점은 정말 많은데, 그중에서도 가장 마음에 드는 점은 문서 구조화가 잘 된다는 것이다.
사이드바로 문서들을 체계적으로 분류할 수 있고, 검색 기능도 기본으로 제공된다.
블로그 기능도 있어서 글을 작성하고 관리하기가 편하다.
배포도 아주 간단하다. GitHub Pages나 Vercel 같은 서비스를 이용하면 무료로 호스팅할 수 있다.
특히 GitHub Actions를 사용하면 새 글을 작성하고 올릴 때마다 자동으로 사이트가 업데이트된다.
기존에 워드프레스나 티스토리 같은 블로그 서비스를 사용했었는데, 도큐사우루스는 이것들과는 좀 다르다.
개발자를 위한 기능이 많고, 마크다운으로 글을 쓸 수 있어서 코드를 포함한 기술 문서를 작성하기가 훨씬 편하다.
무엇보다 내가 원하는 대로 커스터마이징할 수 있다는 점이 큰 장점이다.
3) 티스토리와 도큐사우루스 비교
| 항목 | 티스토리 | 도큐사우루스 |
|---|---|---|
| 호스팅 | 무료 호스팅 제공 | 직접 호스팅 필요 |
| 커스터마이징 | 테마 수정 제한적 | 완전한 커스터마이징 가능 |
| 마크다운 | 제한적 지원 | 네이티브 지원 |
| 코드 하이라이팅 | 기본 제공 | 다양한 언어 지원 |
| 버전 관리 | 불가능 | Git 통한 버전 관리 가능 |
| 학습 곡선 | 낮음 | 중간~높음 |
4) 기술 스택
- Docusaurus: 3.7.0
- React: 18.2.0 (다운그레이드됨)
- TypeScript: 5.6.2
- Node.js: ≥18.0
- Hosting: Vercel
참고: Docusaurus 3.7은 원래 React 19를 지원하도록 설계되었으나,
TailwindCSS 등 일부 라이브러리와의 호환성 문제로 인해
React 18.2.0으로 다운그레이드하여 사용.
5) 생성 방법
- 참고로 node.js 18 버전 이상이 설치되어 있어야 한다.
npx create-docusaurus@latest my-website classic
cd my-website
npm run start
다음 시간에는 프로젝트에 도메인을 연결하고, 배포해서 실제로 웹 서버를 띄우는 작업을 진행할 예정이다.